PyVistaとSphinx#

PyVistaを活用して,素晴らしいインタラクティブなWebドキュメントを作成することができます.

ちなみに

このチュートリアルのセクションは,PyVistaドキュメントの Plotting ThemesSphinx PyVista Plot Directive の章から採用されたものです.

ドキュメントに3Dプロットを動的に生成する#

PyVistaを使うと, Matplotlib plot_directive と同じように,Sphinx内で静的または動的な画像を直接生成することができます.手動でプロットを作成して,コードセクションの後に追加するのではなく,代わりに動的に画像を生成して,ドキュメントの中に直接埋め込むことができるのです.これは sphinx-gallery ともシームレスに動作しますので, Matplotlib Example Gallery のようなノートブックのサンプルを作成することができます.

さらに副次的な利点として,生成したドキュメントがプロジェクトの API と一致することを確認できます.これを GitHub ワークフロー に組み込むと,次のようになります.

このセクションでは,以下の項目について説明します.

静的プロット - Sphinx PyVista プロットディレクティブ#

Sphinxを使用してドキュメントをビルドする際に, conf.py に以下を追加すると, pyvista-plot ディレクティブを使用して,sphinx内でPyVistaプロットの静止画像を生成することができます.

extensions = [
    "sphinx.ext.napoleon",
    "pyvista.ext.plot_directive",
]

そうすれば,sphinxのドキュメントファイルの中で,plottingディレクティブを発行することができます:

.. pyvista-plot::
   :caption: A sphere
   :include-source: True

   >>> import pyvista
   >>> sphere = pyvista.Sphere()
   >>> out = sphere.plot()

以下のように表示されます.

>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> out = sphere.plot()
../../_images/index-1_00_003.png

これはデフォルトの球体#

Jupyter Sphinx拡張を使った動的プロッティング#

PyVistaは jupyter-sphinx 拡張もサポートしています.この拡張機能を使うと, jupyter-execute ディレクティブを使って,sphinx *.rst ファイル内のコードブロックを実行することができます:

.. jupyter-execute::

   name = 'world'
   print('hello ' + name + '!')

以下のように表示されます:

name = 'world'
print('hello ' + name + '!')
hello world!

同様に,通常ノートブック内でレンダリングされるPyVistaからの出力は, jupyter-execute ディレクティブの出力セルにレンダリングされます.例えば, pythreejs バックエンドを使用したプロットは次のようになります.

.. jupyter-execute::

   from pyvista import examples
   dataset = examples.download_urn()
   dataset.plot(color='tan', jupyter_backend='pythreejs', window_size=(700, 400))

以下のように表示されます:

from pyvista import examples
dataset = examples.download_urn()
dataset.plot(color='tan', jupyter_backend='pythreejs', window_size=(700, 400))

PyVistaで Panel バックエンドを使用する#

PyVistaは vtk.js jupyterlab plotting backendとして panel <https://github.com/holoviz/panel>`_ libraryの使用をサポートしています.このライブラリは,スタンドアロンのVTKビューアとして,あるいは緊密に連携した ``pyvista plotting backendとして使用することが可能です. 例えば,Jupyterノートブック環境では, plotPlotter.showjupyter_backend='panel' を渡すと,自動的にJuptyerと panel でプロットできるようになります.

例えば,これは PyVista のロゴです:

.. jupyter-execute::

   from pyvista import demos
   demos.plot_logo(background='white', jupyter_backend='panel')

以下のようにドキュメント内に表示されています:

from pyvista import demos
demos.plot_logo(background='white', jupyter_backend='panel')

使用例と使用方法#

Jupyterノートブック内で panel を使用するには2つの方法があります. mesh.plot()jupyter_backend を設定することにより,プロットごとに使用することができます.

.. jupyter-execute::

    import pyvista as pv
    from pyvista import examples

    # create a point cloud from lidar data and add height scalars
    dataset = examples.download_lidar()
    point_cloud = pv.PolyData(dataset.points[::100])
    point_cloud['height'] = point_cloud.points[:, 2]
    point_cloud.plot(window_size=[500, 500],
                     jupyter_backend='panel',
                     cmap='jet',
                     point_size=2,
                     background='w')

そして,これがSphinxでの出力結果です:

import pyvista as pv
from pyvista import examples

# create a point cloud from lidar data and add height scalars
dataset = examples.download_lidar()
point_cloud = pv.PolyData(dataset.points[::100])
point_cloud['height'] = point_cloud.points[:, 2]
point_cloud.plot(window_size=[500, 500],
                 jupyter_backend='panel',
                 cmap='jet',
                 point_size=2,
                 background='w')

または,プロットバックエンドとグローバルテーマを設定するコードを最初に隠すことができます:

.. jupyter-execute::
    :hide-code:

    import pyvista as pv

    # Set the global jupyterlab backend.  All plots from this point
    # onward will use the ``panel`` backend and do not have to be
    # specified in ``show``
    pv.set_jupyter_backend('panel')

そして,任意のデータセットに対して plot を直接実行するようにします:

.. jupyter-execute::

   from pyvista import examples
   dataset = examples.download_dragon()
   dataset.plot(cpos="xy")

以下のように見えます:

from pyvista import examples
dataset = examples.download_dragon()
dataset.plot(cpos="xy")

注釈

You have the option of choosing panel or pythreejs as a backend, but you might find that panel has better support as it's being actively developed.

演習#

以下でリポジトリをクローンするか, pyvista/pyvista-doc-example リポジトリを使って,自分自身でSphinxのドキュメントを生成します:

git clone https://github.com/pyvista/pyvista-doc-example

または,単にリポジトリをダウンロードします:

ドキュメントをビルドします#

pyvista/pyvista-doc-example をダウンロードしたら,そのディレクトリにcdして,ドキュメントのビルド要件を次のようにインストールします.

cd pyvista-doc-example
pip install -r requirements_docs.txt

最後に,次のようにしてローカルにドキュメントをビルドします:

cd doc
make html

または,Windowsの場合:

cd doc
make.bat

doc/_build ディレクトリの中に,生成されたドキュメントがあります.ブラウザで index.html を開くと,ドキュメントが表示されます.

Sphinx-Galleryによるギャラリー